Documentation | Bounties

Omnigres makes Postgres a developer-first application platform. You can deploy a single database instance and it can host your entire application, scaling as needed.

• Running application logic inside or next to the database instance
• Deployment provisioning (Git, containers, etc.)
• Database instance serves HTTP, WebSocket and other protocols
• In-memory and volatile on-disk caching
• Routine application building blocks (authentication, authorization, payments, etc.)
• Database-modeled application logic via reactive queries
• Automagic remote APIs and form handling
• Live data updates

• Omnigres blog

The fastest way to try Omnigres out is by using its container image:

docker volume create omnigres
docker run --name omnigres --mount source=omnigres,target=/var/lib/postgresql/data \
           -p 127.0.0.1:5432:5432 -p 127.0.0.1:8080:8080 -p 127.0.0.1:8081:8081 --rm ghcr.io/omnigres/omnigres-17:latest
# Now you can connect to it:
psql -h localhost -p 5432 -U omnigres omnigres # password is `omnigres`

Postgres parameters such as database, user or password can be overridden as per the "Environment Variables" section in postgres image instructions

You can access the default HTTP server at localhost:8081

If you can't use the pre-built image (for example, you are running a fork or made changes), you can build the image yourself:

# Build the image
DOCKER_BUILDKIT=1 docker build . -t ghcr.io/omnigres/omnigres

Omnigres extensions can also be downloaded and installed in any postgres installation with file system access.

Here we expect you are running the container image, which has omni_httpd and omni_web extensions provisioned by default.

Let's start with a traditional example. Here we will instruct the handler that is provisioned by omni_httpd by default to use the enclosed query to greet the world.

Below, we'll show examples in Python and plain SQL (or PL/pgSQL). Support for more languages is coming!

$ curl localhost:8081
Hello, world!

from omni_python import pg
from flask import Flask
from omni_http.omni_httpd import flask

app = Flask('myapp')


@app.route('/')
def hello():
    return "Hello, world!"


handle = pg(flask.Adapter(app))

insert into omni_httpd.urlpattern_router (match, handler)
values (omni_httpd.urlpattern('/'), 'my_handler'::regproc);

create function my_handler()
  returns omni_httpd.http_outcome
  return omni_httpd.http_response('Hello world!');

insert into omni_httpd.urlpattern_router (match, handler)
values (omni_httpd.urlpattern('/'), 'my_handler'::regproc);

Now, let's make it more personal and let it greet the requester by name.

$ curl "localhost:8081?name=John"
Hello, John!

from flask import request  # we need to access `request`


@app.route('/')
def hello():
    return f"Hello, {request.args.get('name', 'world')}!"

update omni_httpd.handlers
set
    query =
        $$select omni_httpd.http_response('Hello, ' || 
                   coalesce(omni_web.param_get(request.query_string, 'name'), 'world') || '!')
          from request$$;

This, of course, only barely scratches the surface, but it may give you a very high-level concept of how Omnigres web services can be built.

For a more complex example, that uses the underlying database and employs more real-world layout, check out this MOTD service example.

A collection of extensions that improve Postgres and turn it into a comprehensive business runtime.

To build and run Omnigres, you would need:

• a recent C compiler
• OpenSSL 3.2 (optional, will be built if not available)
• cmake >= 3.25.1
• (optionally, to use omni_containers or run a full set of tests) a recent version of Docker
• (optionally, to use omni_kube or run a full set of tests), kube config file in default location (~/.kube/config)

cmake -S . -B build
cmake --build build --parallel
cd build && make -j psql_<COMPONENT_NAME> # for example, `psql_omni_id`

To install extensions into your target Postgres:

cmake --build build --parallel --target install_extensions
# Or, individually,
cmake --build build --parallel --target install_<COMPONENT_NAME>_extension

One can pass an exclusion list or an explicit inclusion list to the first cmake step:

cmake -S . -B build -DOMNIGRES_EXCLUDE="omni_txn;omni_xml"
cmake -S . -B build -DOMNIGRES_INCLUDE="omni_httpd"

By default, all modules are included. Please note that if an extension is effectively excluded and is required by an included one, cmake will fail with an error like this:

omni_http required by omni_httpc but is effectively excluded

cmake -S . -B build -DPython3_EXECUTABLE=/path/to/python

rm -rf .pg build

# in the build directory
CTEST_PARALLEL_LEVEL=$(nproc) make -j $(nproc) all test

Once you are ready to contribute, please check out the contribution guidelines.